#%RAML 1.0 ResourceType
# collection.raml
#the raml making use of this collection must include the following
#traits:
# - orderable: !include traits/orderable.raml
# - pageable:  !include traits/pageable.raml
# - searchable: !include traits/searchable.raml
      description: Collection of <<resourcePathName|!singularize>> items.
      is: [language]

      post:
        description: Create a new <<resourcePathName|!singularize>> item.
        body:
          application/json:
            type: <<schemaItem>>
            example:
              strict: false
              value: <<exampleItem>>
        responses:
          201:
            description: "Returns a newly created item, with server-controlled fields like 'id' populated"
            headers:
              Location:
                description: URI to the created <<resourcePathName|!singularize>> item
            body:
              application/json:
                example: <<exampleItem>>
          400:
            description: "Bad request, e.g. malformed request body or query parameter. Details of the error (e.g. name of the parameter or line/character number with malformed data) provided in the response."
            body:
              text/plain:
                example: |
                  "unable to add <<resourcePathName|!singularize>> -- malformed JSON at 13:3"
          401:
            description: "Not authorized to perform requested action"
            body:
              text/plain:
                example: "unable to create <<resourcePathName>> -- unauthorized"
          500:
            description: "Internal server error, e.g. due to misconfiguration"
            body:
              text/plain:
                example: "Internal server error, contact administrator"
